Exposed Computation Overview

The Exposed Computation Web Service is exposed to give an external application access to OIPA's robust math engine. A call to this Web Service can be used to execute a calculation and return result values in the SOAP response XML.

A request to this service takes two text parameters:

  • ComputationID – An identifier for a record in the AsExposedComputation table.
  • XML – A text parameter that is treated as an XML document by the service.

The service processes a math engine based on the configuration for the passed ComputationID parameter. The XML document can be used to feed extra dynamic parameters to a request. Response from the call is also driven by the configuration of the ComputationID in the request.

Request Flow

Request Flow Diagram

The Exposed Computation Web Service processes a request with the following steps:

  1. Parse policy number and effective date from the incoming XML document. Set policy context if policy information is supplied.
  2. Load AsExposedComputation record for the ComputationID from the request.
  3. Load ExposedComputation business rule (from AsBusinessRules table). If a policy is present, then load the business rule override for the plan of the policy.
  4. Do policy valuation if a policy is present and exposed computation business rule is configured to do so.
  5. Execute math from the Input configuration in the exposed computation business rule. If a policy is present, then use the data present in it and its plan.
  6. Build response XML from the Output configuration in the exposed computation business rule AsExposedComputation Table

The AsExposedComputation table is a configuration table for storing exposed computations. An AsExposedComputation record will have a unique ComputationID value. The other relevant column in this table is the RuleName column, which is the name of the rule in the AsBusinessRules table that contains the configuration for processing.

Exposed Computation Business Rule

The RuleName from the AsExposedComputation table for the exposed computation request is used to load an AsBusinessRule record that contains the configuration for what to process. The ExposedComputation business rule is set-up in much the same way as the Calculate business rules are configured for calculating segments. There is an Input element that contains the math variables configuration for processing the math engine. The math variables should be configured the same way as any other math section in the system. There is also an Output element, which contains the mappings for the input variables to output in the response.

Below is a sample of a simple ExposedComputation configuration:

<ExposedComputation>
    <Input>
        <MathVariables>
            <MathVariable VARIABLENAME="Variable1" TYPE="VALUE" DATATYPE="TEXT">TestValue</MathVariable>
        </MathVariables>
    </Input>
    <Output>
        <Mappings>
            <Mapping OUTPUTNAME="Result1">Variable1</Mapping>
        </Mappings>
    </Output>
</ExposedComputation>

The Input element contains the math to process, while the Output element pulls the math variable into the output for "Result1". The response of the exposed computation request will contain the value for "Result1".

Valuation

The exposed computation also has the ability to do valuation. The configuration for this support is below:

<ExposedComputation VALUATION="Yes">
. . .
</ExposedComputation>

By adding this attribute, valuation is run before executing math. This makes available all valuation FIELDs (Valuation:Policy:CashValue, Valuation:Fund:FundGUID:CashValue, etc.) to the math configuration. Valuation can only be executed if the request is being processed in the context of a policy.

When processing valuation that may contain variable funds, there is also the ability for using the nearest NUVs for the funds. This is achieved through the following configuration:

<ExposedComputation VALUATION="Yes" NEARESTNUV="Yes">
. . .
</ExposedComputation>

Exposed Computation SOAP Messages

SOAP Request Input Parameters

When making an ExposedComputation request, the second parameter available is a String that the service treats as an XML document. This XML contains parameters that can be used as Parameter FIELD values when executing the math engine.

Example 

<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:exp="http://ExposedComputation"> 
    <soapenv:Header>
        <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <wsse:UsernameToken wsu:Id="UsernameToken-1" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
                <wsse:Username>tester</wsse:Username>
                <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">tester</wsse:Password>
                <wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">FRkBB/REsT/4ThQzEjoiUQ==</wsse:Nonce>
                <wsu:Created>2011-07-01T22:39:59.640Z</wsu:Created>
            </wsse:UsernameToken>
        </wsse:Security>
    </soapenv:Header>
    <soapenv:Body>
        <exp:processExposedComputation>
            <computationId>BC-Exp1</computationId>
            <inputXml>
                <![CDATA[
<Request>
<Parameters>
<Parameter NAME="PolicyNumber">VDA31011809</Parameter>
<Parameter NAME="EffectiveDate">01/01/2009</Parameter>
<Parameter NAME="InputVariable1">TestValue1</Parameter>
</Parameters>
</Request>]]>
            </inputXml>
        </exp:processExposedComputation>
    </soapenv:Body>
</soapenv:Envelope>

PolicyNumber

Inclusion of a "PolicyNumber" parameter tells the exposed computation that it is being processed for a policy. The exposed computation business rule is now overridable by plan with this parameter, and the math engine will have access to Policy and Plan FIELD variables for that policy when executed. This parameter is also required if the exposed computation is configured to perform valuation during the request.

EffectiveDate

An "EffectiveDate" parameter can be included when an exposed computation executes valuation during the request. This date will be used as the valuation date during valuation. If this parameter is not defined and valuation is still executed, the valuation date will default to the system date.

Below is the expected format for the XML parameter in the request:

<Parameters>
    <Parameter NAME="PolicyNumber">POL12345</Parameter>
    <Parameter NAME="EffectiveDate">01/01/2009</Parameter>
</Parameters>

SOAP Response

The data returned in the SOAP response XML from a call to exposed computation is built from the <Output> mappings configured in the exposed computation rule. The root element from the response is the ComputationID from the request. Each child element of the root is the mapping from the output configuration with its math value as the element text. For example, refer to the ComputationID "EC_Test" with the below exposed computation configuration:

<ExposedComputation>
    <Input>
        <MathVariables>
            <MathVariable VARIABLENAME="Variable1" TYPE="VALUE" DATATYPE="TEXT">TestValue1</MathVariable>
            <MathVariable VARIABLENAME="Variable2" TYPE="VALUE" ATATYPE="TEXT">TestValue2</MathVariable>
        </MathVariables>
    </Input>
    <Output>
        <Mappings>
            <Mapping OUTPUTNAME="Result1">Variable1</Mapping>
            <Mapping OUTPUTNAME="Result2">Variable2</Mapping>
        </Mappings>
    </Output>
</ExposedComputation>
 
<!-- This will be the response XML: -->
 
<EC_Test>
    <Result1>TestValue1</Result1>
    <Result2>TestValue2</Result2>
</EC_Test>